<!DOCTYPE html>
<html lang=zh>
<head><meta name="generator" content="Hexo 3.8.0">
  <meta charset="utf-8">
  
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no, minimal-ui">
  <meta name="renderer" content="webkit">
  <meta http-equiv="Cache-Control" content="no-transform">
  <meta http-equiv="Cache-Control" content="no-siteapp">
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="black">
  <meta name="format-detection" content="telephone=no,email=no,adress=no">
  <!-- Color theme for statusbar -->
  <meta name="theme-color" content="#000000">
  <!-- 强制页面在当前窗口以独立页面显示,防止别人在框架里调用页面 -->
  <meta http-equiv="window-target" content="_top">
  
  
  <title>Sphinx+ReStructuredText制作手册文档 | 王竹兴 | Blob</title>
  <meta name="description" content="Sphinx简介   概述 ​	Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发。 ​	新版的Python文档 就是由Sphinx生成的，并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.   特性  丰富的输出格式: 支持 HTML (包括 Win">
<meta name="keywords" content="rst">
<meta property="og:type" content="article">
<meta property="og:title" content="Sphinx+ReStructuredText制作手册文档">
<meta property="og:url" content="http://zhulao.gitee.io/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/index.html">
<meta property="og:site_name" content="王竹兴 | Blog">
<meta property="og:description" content="Sphinx简介   概述 ​	Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发。 ​	新版的Python文档 就是由Sphinx生成的，并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.   特性  丰富的输出格式: 支持 HTML (包括 Win">
<meta property="og:locale" content="zh-CN">
<meta property="og:updated_time" content="2019-05-02T09:57:11.722Z">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="Sphinx+ReStructuredText制作手册文档">
<meta name="twitter:description" content="Sphinx简介   概述 ​	Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发。 ​	新版的Python文档 就是由Sphinx生成的，并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.   特性  丰富的输出格式: 支持 HTML (包括 Win">
  <!-- Canonical links -->
  <link rel="canonical" href="http://zhulao.gitee.io/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/index.html">
  
    <link rel="alternate" href="/atom.xml" title="王竹兴 | Blog" type="application/atom+xml">
  
  
    <link rel="icon" href="/favicon.png" type="image/x-icon">
  
  <link rel="stylesheet" href="/blog/css/style.css">
  
  
  
  
</head>


<body class="main-center" itemscope itemtype="http://schema.org/WebPage">
  <header class="header" itemscope itemtype="http://schema.org/WPHeader">
  <div class="slimContent">
    <div class="navbar-header">
      
      
      <div class="profile-block text-center">
        <a id="avatar" href="https://github.com/wzx3" target="_blank">
          <img class="img-circle img-rotate" src="/blog/images/avatar.jpeg" width="200" height="200">
        </a>
        <h2 id="name" class="hidden-xs hidden-sm">王竹兴</h2>
        <h3 id="title" class="hidden-xs hidden-sm hidden-md"></h3>
        <small id="location" class="text-muted hidden-xs hidden-sm"><i class="icon icon-map-marker"></i> XiaMen, China</small>
      </div>
      
      <div class="search" id="search-form-wrap">

    <form class="search-form sidebar-form">
        <div class="input-group">
            <input type="text" class="search-form-input form-control" placeholder="搜索">
            <span class="input-group-btn">
                <button type="submit" class="search-form-submit btn btn-flat" onclick="return false;"><i class="icon icon-search"></i></button>
            </span>
        </div>
    </form>
    <div class="ins-search">
  <div class="ins-search-mask"></div>
  <div class="ins-search-container">
    <div class="ins-input-wrapper">
      <input type="text" class="ins-search-input" placeholder="想要查找什么..." x-webkit-speech>
      <button type="button" class="close ins-close ins-selectable" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">×</span></button>
    </div>
    <div class="ins-section-wrapper">
      <div class="ins-section-container"></div>
    </div>
  </div>
</div>


</div>
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#main-navbar" aria-controls="main-navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
    </div>
    <nav id="main-navbar" class="collapse navbar-collapse" itemscope itemtype="http://schema.org/SiteNavigationElement" role="navigation">
      <ul class="nav navbar-nav main-nav menu-highlight">
        
        
        <li class="menu-item menu-item-home">
          <a href="/blog/.">
            
            <i class="icon icon-home-fill"></i>
            
            <span class="menu-title">首页</span>
          </a>
        </li>
        
        
        <li class="menu-item menu-item-archives">
          <a href="/blog/archives">
            
            <i class="icon icon-archives-fill"></i>
            
            <span class="menu-title">归档</span>
          </a>
        </li>
        
        
        <li class="menu-item menu-item-categories">
          <a href="/blog/categories">
            
            <i class="icon icon-folder"></i>
            
            <span class="menu-title">分类</span>
          </a>
        </li>
        
        
        <li class="menu-item menu-item-tags">
          <a href="/blog/tags">
            
            <i class="icon icon-tags"></i>
            
            <span class="menu-title">标签</span>
          </a>
        </li>
        
        
        <li class="menu-item menu-item-repository">
          <a href="/blog/repository">
            
            <i class="icon icon-project"></i>
            
            <span class="menu-title">项目</span>
          </a>
        </li>
        
        
        <li class="menu-item menu-item-about">
          <a href="/blog/about">
            
            <i class="icon icon-cup-fill"></i>
            
            <span class="menu-title">关于</span>
          </a>
        </li>
        
      </ul>
      
	
    <ul class="social-links">
    	
        <li><a href="https://github.com/wzx3" target="_blank" title="Github" data-toggle="tooltip" data-placement="top"><i class="icon icon-github"></i></a></li>
        
        <li><a href="/blog/atom.xml" target="_blank" title="Rss" data-toggle="tooltip" data-placement="top"><i class="icon icon-rss"></i></a></li>
        
    </ul>

    </nav>
  </div>
</header>

  
    <aside class="sidebar" itemscope itemtype="http://schema.org/WPSideBar">
  <div class="slimContent">
    
      <div class="widget">
    <h3 class="widget-title">公告</h3>
    <div class="widget-body">
        <div id="board">
            <div class="content">
                <p>人生最快意的事情之一, 就是你比别人牛逼, 然后静静的看别人在你面前装逼。</p>
            </div>
        </div>
    </div>
</div>

    
      
  <div class="widget">
    <h3 class="widget-title">分类</h3>
    <div class="widget-body">
      <ul class="category-list"><li class="category-list-item"><a class="category-list-link" href="/blog/categories/便签/">便签</a><span class="category-list-count">2</span></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/教程/">教程</a><span class="category-list-count">22</span></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/游记/">游记</a><span class="category-list-count">1</span></li><li class="category-list-item"><a class="category-list-link" href="/blog/categories/随笔/">随笔</a><span class="category-list-count">6</span></li></ul>
    </div>
  </div>


    
      
  <div class="widget">
    <h3 class="widget-title">标签云</h3>
    <div class="widget-body tagcloud">
      <a href="/blog/tags/DL/" style="font-size: 13.25px;">DL</a> <a href="/blog/tags/Debug/" style="font-size: 13.5px;">Debug</a> <a href="/blog/tags/Doc/" style="font-size: 13px;">Doc</a> <a href="/blog/tags/Hexo/" style="font-size: 13.25px;">Hexo</a> <a href="/blog/tags/Links/" style="font-size: 13px;">Links</a> <a href="/blog/tags/Linux/" style="font-size: 13.25px;">Linux</a> <a href="/blog/tags/Mac/" style="font-size: 13px;">Mac</a> <a href="/blog/tags/bazel/" style="font-size: 13px;">bazel</a> <a href="/blog/tags/c-c/" style="font-size: 13.75px;">c/c++</a> <a href="/blog/tags/git/" style="font-size: 13px;">git</a> <a href="/blog/tags/rst/" style="font-size: 13px;">rst</a> <a href="/blog/tags/scripts/" style="font-size: 13.75px;">scripts</a> <a href="/blog/tags/ssh/" style="font-size: 13px;">ssh</a> <a href="/blog/tags/国学经典/" style="font-size: 13px;">国学经典</a> <a href="/blog/tags/持续集成/" style="font-size: 13.25px;">持续集成</a> <a href="/blog/tags/科幻小说/" style="font-size: 14px;">科幻小说</a>
    </div>
  </div>

    
      
  <div class="widget">
    <h3 class="widget-title">归档</h3>
    <div class="widget-body">
      <ul class="archive-list"><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2019/05/">五月 2019</a><span class="archive-list-count">6</span></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2019/04/">四月 2019</a><span class="archive-list-count">10</span></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2019/03/">三月 2019</a><span class="archive-list-count">6</span></li><li class="archive-list-item"><a class="archive-list-link" href="/blog/archives/2019/02/">二月 2019</a><span class="archive-list-count">10</span></li></ul>
    </div>
  </div>


    
      
  <div class="widget">
    <h3 class="widget-title">最新文章</h3>
    <div class="widget-body">
      <ul class="recent-post-list list-unstyled no-thumbnail">
        
          <li>
            
            <div class="item-inner">
              <p class="item-category">
                <a class="category-link" href="/blog/categories/随笔/">随笔</a>
              </p>
              <p class="item-title">
                <a href="/blog/2019/05/26/读论语/" class="title">读论语</a>
              </p>
              <p class="item-date">
                <time datetime="2019-05-26T01:45:07.000Z" itemprop="datePublished">2019-05-26</time>
              </p>
            </div>
          </li>
          
          <li>
            
            <div class="item-inner">
              <p class="item-category">
                <a class="category-link" href="/blog/categories/随笔/">随笔</a>
              </p>
              <p class="item-title">
                <a href="/blog/2019/05/20/读变型战争/" class="title">读变型战争</a>
              </p>
              <p class="item-date">
                <time datetime="2019-05-20T15:51:57.000Z" itemprop="datePublished">2019-05-20</time>
              </p>
            </div>
          </li>
          
          <li>
            
            <div class="item-inner">
              <p class="item-category">
                <a class="category-link" href="/blog/categories/随笔/">随笔</a>
              </p>
              <p class="item-title">
                <a href="/blog/2019/05/20/读星际远征/" class="title">读黑客横行</a>
              </p>
              <p class="item-date">
                <time datetime="2019-05-20T15:40:09.000Z" itemprop="datePublished">2019-05-20</time>
              </p>
            </div>
          </li>
          
          <li>
            
            <div class="item-inner">
              <p class="item-category">
                <a class="category-link" href="/blog/categories/教程/">教程</a>
              </p>
              <p class="item-title">
                <a href="/blog/2019/05/15/代码格式化工具-clang-format/" class="title">代码格式化工具:clang-format</a>
              </p>
              <p class="item-date">
                <time datetime="2019-05-15T14:39:51.000Z" itemprop="datePublished">2019-05-15</time>
              </p>
            </div>
          </li>
          
          <li>
            
            <div class="item-inner">
              <p class="item-category">
                <a class="category-link" href="/blog/categories/教程/">教程</a>
              </p>
              <p class="item-title">
                <a href="/blog/2019/05/12/Linux-疑难杂症/" class="title">Linux 疑难杂症</a>
              </p>
              <p class="item-date">
                <time datetime="2019-05-12T02:50:29.000Z" itemprop="datePublished">2019-05-12</time>
              </p>
            </div>
          </li>
          
      </ul>
    </div>
  </div>
  

    
  </div>
</aside>

  
  
<aside class="sidebar sidebar-toc collapse" id="collapseToc" itemscope itemtype="http://schema.org/WPSideBar">
  <div class="slimContent">
    <nav id="toc" class="article-toc">
      <h3 class="toc-title">文章目录</h3>
      <ol class="toc"><li class="toc-item toc-level-3"><a class="toc-link" href="#sphinx简介"><span class="toc-number">1.</span> <span class="toc-text"> Sphinx简介</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#restructuredtext简介"><span class="toc-number">2.</span> <span class="toc-text"> ReStructuredText简介</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#环境搭建"><span class="toc-number">3.</span> <span class="toc-text"> 环境搭建</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#初始化工程"><span class="toc-number">4.</span> <span class="toc-text"> 初始化工程</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#文档编撰"><span class="toc-number">5.</span> <span class="toc-text"> 文档编撰</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#主题设置"><span class="toc-number">6.</span> <span class="toc-text"> 主题设置</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#文档生成"><span class="toc-number">7.</span> <span class="toc-text"> 文档生成</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#文档发布"><span class="toc-number">8.</span> <span class="toc-text"> 文档发布</span></a></li><li class="toc-item toc-level-3"><a class="toc-link" href="#参考文献"><span class="toc-number">9.</span> <span class="toc-text"> 参考文献</span></a></li></ol>
    </nav>
  </div>
</aside>

<main class="main" role="main">
  <div class="content">
  <article id="post-Sphinx-ReStructuredText制作手册文档" class="article article-type-post" itemscope itemtype="http://schema.org/BlogPosting">
    
    <div class="article-header">
      
        
  
    <h1 class="article-title" itemprop="name">
      Sphinx+ReStructuredText制作手册文档
    </h1>
  

      
      <div class="article-meta">
        <span class="article-date">
    <i class="icon icon-calendar-check"></i>
	<a href="/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/" class="article-date">
	  <time datetime="2019-04-30T10:35:27.000Z" itemprop="datePublished">2019-04-30</time>
	</a>
</span>
        
  <span class="article-category">
    <i class="icon icon-folder"></i>
    <a class="article-category-link" href="/blog/categories/教程/">教程</a>
  </span>

        
  <span class="article-tag">
    <i class="icon icon-tags"></i>
	<a class="article-tag-link" href="/blog/tags/rst/">rst</a>
  </span>


        
	<span class="article-read hidden-xs">
	    <i class="icon icon-eye-fill" aria-hidden="true"></i>
	    <span id="busuanzi_container_page_pv">
			<span id="busuanzi_value_page_pv">0</span>
		</span>
	</span>


        <span class="post-comment"><i class="icon icon-comment"></i> <a href="/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/#comments" class="article-comment-link">评论</a></span>
        
	
		<span class="post-wordcount hidden-xs" itemprop="wordCount">字数统计: 1,469(字)</span>
	
	
		<span class="post-readcount hidden-xs" itemprop="timeRequired">阅读时长: 7(分)</span>
	

      </div>
    </div>
    <div class="article-entry marked-body" itemprop="articleBody">
      
        <h3 id="sphinx简介"><a class="markdownIt-Anchor" href="#sphinx简介"></a> Sphinx简介</h3>
<ul>
<li>
<p><strong>概述</strong></p>
<p>​	<code>Sphinx</code> 是一种<strong>文档工具</strong>，它可以令人轻松的撰写出清晰且优美的文档, 由 <strong>Georg Brandl</strong> 在BSD 许可证下开发。</p>
<p>​	<strong>新版的Python文档 就是由Sphinx生成的</strong>，并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.</p>
</li>
<li>
<p><strong>特性</strong></p>
<ul>
<li><strong>丰富的输出格式</strong>: 支持 <code>HTML</code> (包括 Windows 帮助文档), <code>LaTeX</code> (可以打印PDF版本), <code>manual pages</code>（man 文档）, <code>纯文本</code></li>
<li><strong>完备的交叉引用</strong>: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息</li>
<li><strong>明晰的分层结构</strong>: 可以轻松的定义<strong>文档树</strong>,并<strong>自动化链接同级/父级/下级文章</strong></li>
<li><strong>美观的自动索引</strong>: 可自动生成美观的模块索引</li>
<li><strong>精确的语法高亮</strong>: 基于 <code>Pygments</code> 自动生成语法高亮</li>
<li><strong>开放的扩展</strong>: <strong>支持代码块的自动测试</strong>,并包含Python模块的自述文档(API docs)等</li>
</ul>
</li>
</ul>
<h3 id="restructuredtext简介"><a class="markdownIt-Anchor" href="#restructuredtext简介"></a> ReStructuredText简介</h3>
<ul>
<li>
<p><strong>概述</strong></p>
<p>​	<code>ReStructuredText</code> <strong>是扩展名为.rst的纯文本文件</strong>，含义为&quot;重新构建的文本&quot;，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。<br>
​	<code>Docutils</code> 能够<strong>从Python程序中提取注释和信息，格式化成程序文档</strong>。</p>
<p>​	<code>.rst 文件</code>是<strong>轻量级标记语言的一种</strong>，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式.</p>
</li>
</ul>
<h3 id="环境搭建"><a class="markdownIt-Anchor" href="#环境搭建"></a> 环境搭建</h3>
<ul>
<li>
<p>安装<code>Sphinx</code></p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">brew install sphinx</span><br><span class="line">sudo pip install sphinx</span><br></pre></td></tr></table></figure>
</li>
<li>
<p>安装<code>restructuredtext-lint</code></p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">sudo pip install restructuredtext-lint</span><br></pre></td></tr></table></figure>
</li>
<li>
<p>编辑器推荐使用<code>VS Code</code></p>
<ul>
<li><strong>安装插件支持.rst文本</strong>: 扩展商店搜索 <strong>ReStructuredText</strong>、安装</li>
</ul>
</li>
</ul>
<h3 id="初始化工程"><a class="markdownIt-Anchor" href="#初始化工程"></a> 初始化工程</h3>
<ul>
<li>
<p><code>github</code>上创建工程, 如: <strong>rst-tutorial</strong>, 拉取到本地并用 <strong>vs code</strong> 打开。</p>
</li>
<li>
<p>初始化工程</p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">$</span><span class="bash"> sphinx-quickstart</span></span><br></pre></td></tr></table></figure>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br></pre></td><td class="code"><pre><span class="line"><span class="meta">#</span><span class="bash"> 初始化过程, 简单设置后一路回车~</span></span><br><span class="line">Welcome to the Sphinx 1.8.5 quickstart utility.</span><br><span class="line"></span><br><span class="line">Please enter values for the following settings (just press Enter to</span><br><span class="line">accept a default value, if one is given in brackets).</span><br><span class="line"></span><br><span class="line">Selected root path: .</span><br><span class="line"></span><br><span class="line">You have two options for placing the build directory for Sphinx output.</span><br><span class="line">Either, you use a directory "_build" within the root path, or you separate</span><br><span class="line">"source" and "build" directories within the root path.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Separate <span class="built_in">source</span> and build directories (y/n) [n]: </span></span><br><span class="line"></span><br><span class="line">Inside the root directory, two more directories will be created; "_templates"</span><br><span class="line">for custom HTML templates and "_static" for custom stylesheets and other static</span><br><span class="line">files. You can enter another prefix (such as ".") to replace the underscore.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Name prefix <span class="keyword">for</span> templates and static dir [_]: </span></span><br><span class="line"></span><br><span class="line">The project name will occur in several places in the built documentation.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Project name: ReStructuredText Tutorial</span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Author name(s): wzx3</span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Project release []: 0.0.1</span></span><br><span class="line"></span><br><span class="line">If the documents are to be written in a language other than English,</span><br><span class="line">you can select a language here by its language code. Sphinx will then</span><br><span class="line">translate text that it generates into that language.</span><br><span class="line"></span><br><span class="line">For a list of supported codes, see</span><br><span class="line">http://sphinx-doc.org/config.html#confval-language.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Project language [en]: zh</span></span><br><span class="line"></span><br><span class="line">The file name suffix for source files. Commonly, this is either ".txt"</span><br><span class="line">or ".rst".  Only files with this suffix are considered documents.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Source file suffix [.rst]: </span></span><br><span class="line"></span><br><span class="line">One document is special in that it is considered the top node of the</span><br><span class="line">"contents tree", that is, it is the root of the hierarchical structure</span><br><span class="line">of the documents. Normally, this is "index", but if your "index"</span><br><span class="line">document is a custom template, you can also set this to another filename.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Name of your master document (without suffix) [index]: </span></span><br><span class="line">Indicate which of the following Sphinx extensions should be enabled:</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> autodoc: automatically insert docstrings from modules (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> doctest: automatically <span class="built_in">test</span> code snippets <span class="keyword">in</span> doctest blocks (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> todo: write <span class="string">"todo"</span> entries that can be shown or hidden on build (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> coverage: checks <span class="keyword">for</span> documentation coverage (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> mathjax: include math, rendered <span class="keyword">in</span> the browser by MathJax (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> ifconfig: conditional inclusion of content based on config values (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> viewcode: include links to the <span class="built_in">source</span> code of documented Python objects (y/n) [n]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: </span></span><br><span class="line"></span><br><span class="line">A Makefile and a Windows command file can be generated for you so that you</span><br><span class="line">only have to run e.g. `make html' instead of invoking sphinx-build</span><br><span class="line">directly.</span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Create Makefile? (y/n) [y]: </span></span><br><span class="line"><span class="meta">&gt;</span><span class="bash"> Create Windows <span class="built_in">command</span> file? (y/n) [y]: </span></span><br><span class="line"></span><br><span class="line">Creating file ./conf.py.</span><br><span class="line">Creating file ./index.rst.</span><br><span class="line">Creating file ./Makefile.</span><br><span class="line">Creating file ./make.bat.</span><br><span class="line"></span><br><span class="line">Finished: An initial directory structure has been created.</span><br><span class="line"></span><br><span class="line">You should now populate your master file ./index.rst and create other documentation</span><br><span class="line">source files. Use the Makefile to build the docs, like so:</span><br><span class="line">   make builder</span><br><span class="line">where "builder" is one of the supported builders, e.g. html, latex or linkcheck.</span><br></pre></td></tr></table></figure>
<p>初始化完毕后会在工程下生成<code>conf.py</code> <code>index.rst</code> <code>make.bat</code> <code>Makefile</code>四个文件。</p>
<p>可通过<code>VS Code</code>编辑器右上角第一个按钮或按快捷键 <strong>Command+K Command+R</strong> 进行效果预览。</p>
</li>
</ul>
<h3 id="文档编撰"><a class="markdownIt-Anchor" href="#文档编撰"></a> <strong>文档编撰</strong></h3>
<ul>
<li>
<p>示例文档</p>
<p>可参考 <a href="https://github.com/wzx3/rst-tutorial" target="_blank" rel="noopener">ReStructuredText Tutorial</a></p>
</li>
</ul>
<h3 id="主题设置"><a class="markdownIt-Anchor" href="#主题设置"></a> <strong>主题设置</strong></h3>
<ul>
<li>
<p><a href="http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes" target="_blank" rel="noopener">官方内置主题</a> 默认是设置的 <code>alabaster</code> 主题</p>
</li>
<li>
<p>个人觉得官方内置的主题都不好看, 这里推荐 <code>sphinx_rtd_theme</code> 主题</p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">sudo pip install sphinx_rtd_theme</span><br></pre></td></tr></table></figure>
<p>编辑<code>conf.py</code>文件, 修改:</p>
<figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">html_theme = <span class="string">'sphinx_rtd_theme'</span></span><br></pre></td></tr></table></figure>
</li>
</ul>
<h3 id="文档生成"><a class="markdownIt-Anchor" href="#文档生成"></a> 文档生成</h3>
<ul>
<li>
<p>工程目录下执行</p>
<figure class="highlight shell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">make clean &amp;&amp; make html</span><br></pre></td></tr></table></figure>
<p>支持生成的格式文本有: <code>dirhtml</code>,<code>singlehtml</code>,<code>epub</code>,<code>devhelp</code>,<code>latex</code>,<code>man</code>,<code>texinfo</code>,<code>text</code>等</p>
</li>
<li>
<p>预览</p>
<p>生成的<code>html</code>文件在 <strong>./build/html/</strong> 目录下</p>
</li>
</ul>
<h3 id="文档发布"><a class="markdownIt-Anchor" href="#文档发布"></a> 文档发布</h3>
<ul>
<li>
<p>在 <a href="https://readthedocs.org/accounts/login/" target="_blank" rel="noopener"><strong>redthedoc</strong></a> 注册一个账号</p>
</li>
<li>
<p><a href="https://readthedocs.org/dashboard/import/?" target="_blank" rel="noopener"><strong>导入项目</strong></a></p>
<ul>
<li>可直接导入<code>github</code>上的项目</li>
<li>默认文档为<code>en</code>为网址链接缀, 若文档为中文则导入时最好指定是**<code>Chinese</code>**</li>
</ul>
</li>
<li>
<p>导入完毕后点击<code>Build Version</code>按钮, 完成构建</p>
<p><strong>这个构建一次之后，后续我们在github上的提交不用在重新构建的。它会自动保存更新的，可能需要在push后等1-2分钟</strong>。</p>
</li>
<li>
<p>访问</p>
<ul>
<li>构建完成后, 右侧构建耗时下点 <code>View docs</code> 链接即可访问到发布后的文档链接</li>
<li>本人制作的rst文本语法使用文档: <a href="https://rst-tutorial.readthedocs.io/zh/latest/" target="_blank" rel="noopener"><strong>ReStructuredText 快速教程</strong></a></li>
</ul>
</li>
</ul>
<h3 id="参考文献"><a class="markdownIt-Anchor" href="#参考文献"></a> 参考文献</h3>
<ul>
<li><a href="https://www.cnblogs.com/zhaojiedi1992/p/zhaojiedi_python_013_rst_spinx.html" target="_blank" rel="noopener"><strong>sphinx+reStructuredText制作文档</strong></a></li>
</ul>

      
    </div>
    <div class="article-footer">
      <!-- <blockquote class="mt-2x">
  <ul class="post-copyright list-unstyled">
    
    <li class="post-copyright-link hidden-xs">
      <strong>本文链接：</strong>
      <a href="http://zhulao.gitee.io/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/" title="Sphinx+ReStructuredText制作手册文档" target="_blank" rel="external">http://zhulao.gitee.io/blog/2019/04/30/Sphinx-ReStructuredText制作手册文档/</a>
    </li>
    
    <li class="post-copyright-license">
      <strong>版权声明： </strong> 本博客所有文章除特别声明外，均采用 <a href="http://creativecommons.org/licenses/by/4.0/deed.zh" target="_blank" rel="external">CC BY 4.0 CN协议</a> 许可协议。转载请注明出处！
    </li>
  </ul>
</blockquote>


<div class="panel panel-default panel-badger">
  <div class="panel-body">
    <figure class="media">
      <div class="media-left">
        <a href="https://github.com/wzx3" target="_blank" class="img-burn thumb-sm visible-lg">
          <img src="/blog/images/avatar.jpeg" class="img-rounded w-full" alt="">
        </a>
      </div>
      <div class="media-body">
        <h3 class="media-heading"><a href="https://github.com/wzx3" target="_blank"><span class="text-dark">王竹兴</span><small class="ml-1x"></small></a></h3>
        <div></div>
      </div>
    </figure>
  </div>
</div>
 -->

    </div>
  </article>
  
    
  <section id="comments">
  	
  </section>


  
</div>

  <nav class="bar bar-footer clearfix" data-stick-bottom>
  <div class="bar-inner">
  
  <ul class="pager pull-left">
    
    <li class="prev">
      <a href="/blog/2019/05/05/读黑客横行/" title="读黑客横行"><i class="icon icon-angle-left" aria-hidden="true"></i><span>&nbsp;&nbsp;上一篇</span></a>
    </li>
    
    
    <li class="next">
      <a href="/blog/2019/04/26/Python-Graphviz绘制神经网络结构图/" title="Python+Graphviz绘制神经网络结构图"><span>下一篇&nbsp;&nbsp;</span><i class="icon icon-angle-right" aria-hidden="true"></i></a>
    </li>
    
    
    <li class="toggle-toc">
      <a class="toggle-btn collapsed" data-toggle="collapse" href="#collapseToc" aria-expanded="false" title="文章目录" role="button">
        <span>[&nbsp;</span><span>文章目录</span>
        <i class="text-collapsed icon icon-anchor"></i>
        <i class="text-in icon icon-close"></i>
        <span>]</span>
      </a>
    </li>
    
  </ul>
  
  
  
  <div class="bar-right">
    
    <div class="share-component" data-sites="weibo,qq,wechat,facebook,twitter" data-mobile-sites="weibo,qq,qzone"></div>
    
  </div>
  </div>
</nav>
  


</main>

  <footer class="footer" itemscope itemtype="http://schema.org/WPFooter">
	
	
    <ul class="social-links">
    	
        <li><a href="https://github.com/wzx3" target="_blank" title="Github" data-toggle="tooltip" data-placement="top"><i class="icon icon-github"></i></a></li>
        
        <li><a href="/blog/atom.xml" target="_blank" title="Rss" data-toggle="tooltip" data-placement="top"><i class="icon icon-rss"></i></a></li>
        
    </ul>

    <div class="copyright">
    	
        <div class="publishby">
        	Theme by <a href="https://github.com/cofess" target="_blank"> cofess </a>base on <a href="https://github.com/cofess/hexo-theme-pure" target="_blank">pure</a>.
        </div>
    </div>
</footer>
  <script src="//cdn.jsdelivr.net/npm/jquery@1.12.4/dist/jquery.min.js"></script>
<script>
window.jQuery || document.write('<script src="js/jquery.min.js"><\/script>')
</script>
<script src="/blog/js/plugin.min.js"></script>
<script src="/blog/js/application.js"></script>

    <script>
(function (window) {
    var INSIGHT_CONFIG = {
        TRANSLATION: {
            POSTS: '文章',
            PAGES: '页面',
            CATEGORIES: '分类',
            TAGS: '标签',
            UNTITLED: '(未命名)',
        },
        ROOT_URL: '/blog/',
        CONTENT_URL: '/blog/content.json',
    };
    window.INSIGHT_CONFIG = INSIGHT_CONFIG;
})(window);
</script>
<script src="/blog/js/insight.js"></script>





   
<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>





   






</body>
</html>